Add architecture docs and agent coding guidelines - #230
Open
nschimme wants to merge 6 commits into
Open
Conversation
- Author docs/architecture.md providing a high-level overview of the proxy pipeline, core components, and design patterns. - Update AGENTS.md to link to the new architecture doc. - Add a "Coding Guidelines" section to AGENTS.md to document project- specific best practices and common pitfalls for future agents.
|
👋 Jules, reporting for duty! I'm here to lend a hand with this pull request. When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down. I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job! For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with New to Jules? Learn more at jules.google/docs. For security, I will only act on instructions from the user who triggered this task. |
Reviewer's GuideAdds a high-level architecture overview document for MMapper, focused on the proxy data-flow pipeline and main subsystems, and extends AGENTS.md with links plus concrete coding guidelines for signals, string encoding, atomic file saving, memory management, and shortest-path performance. Flow diagram for proxy pipeline data flow in MMapper architectureflowchart LR
subgraph UserSide[User side]
UC["UserClient"] --> USocket["UserSocket"]
USocket --> UTelnet["UserTelnet"]
UTelnet --> ULineFilter["TelnetLineFilter"]
ULineFilter --> UParser["AbstractParser"]
end
subgraph Proxy[Proxy]
UParser --> MTelnet["MudTelnet"]
MTelnet --> MSocket["MudSocket"]
MSocket --> MTelnetBack["MudTelnet"]
MTelnetBack --> MLineFilter["TelnetLineFilter"]
MLineFilter --> MpiFilter["MpiFilter"]
MpiFilter -->|remote edit| RemoteEdit["RemoteEdit"]
MpiFilter -->|game data| MumeXmlParser["MumeXmlParser"]
RemoteEdit --> UTelnetBack["UserTelnet"]
MumeXmlParser --> UTelnetBack
end
subgraph MudSide[MUD side]
MSocket --- MudServer["MudServer"]
end
UTelnetBack --> USocketBack["UserSocket"]
USocketBack --> UCBack["UserClient"]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 1 issue, and left some high level feedback:
- In the Coding Guidelines section, consider briefly explaining the criteria for choosing between Signal2 and Qt signals (e.g., performance-critical vs. UI-only, QObject vs. non-QObject contexts) so that contributors have a clearer decision rule rather than just a default preference.
- The atomic file saving guideline could be strengthened by mentioning typical temp-file usage (e.g., write to a temporary path in the same directory, then rename over the target) to make the intended pattern fully concrete and harder to misapply.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In the Coding Guidelines section, consider briefly explaining the criteria for choosing between Signal2 and Qt signals (e.g., performance-critical vs. UI-only, QObject vs. non-QObject contexts) so that contributors have a clearer decision rule rather than just a default preference.
- The atomic file saving guideline could be strengthened by mentioning typical temp-file usage (e.g., write to a temporary path in the same directory, then rename over the target) to make the intended pattern fully concrete and harder to misapply.
## Individual Comments
### Comment 1
<location path="docs/architecture.md" line_range="30" />
<code_context>
+### Map and World State (`src/map/`, `src/mapdata/`)
+* **MapData**: The primary owner of the map state.
+* **World**: Represents the game world (rooms, exits, areas).
+* **SpatialDb**: An R-Tree based database for fast spatial queries (e.g., "what room is at these coordinates?").
+
+### Rendering (`src/display/`, `src/opengl/`)
</code_context>
<issue_to_address>
**nitpick (typo):** Consider standard hyphenation in 'R-Tree based database'.
Suggest using “an R-tree-based database for fast spatial queries” for more standard compound-adjective hyphenation.
```suggestion
* **SpatialDb**: An R-tree-based database for fast spatial queries (e.g., "what room is at these coordinates?").
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
- Create docs/architecture.md covering the Proxy pipeline, PathMachine states (Approved/Experimenting/Syncing), MapStorage, Rendering, and MUD integration systems. - Update AGENTS.md with a link to the architecture doc and a new "Coding Guidelines" section capturing project-specific best practices (Signal2, string encoding, atomic saving).
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #230 +/- ##
=======================================
Coverage 25.36% 25.36%
=======================================
Files 519 519
Lines 43181 43181
Branches 4705 4705
=======================================
Hits 10952 10952
Misses 32229 32229 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
- Author docs/architecture.md as a high-level technical overview covering the Proxy pipeline, PathMachine logic, MapStorage, Rendering, and MUD integration systems. - Include a domain glossary (GMCP, MPI, Vitals) and a "Common Developer Tasks" guide in docs/architecture.md. - Update AGENTS.md to link to architecture.md and BUILD.md. - Add a "Coding Guidelines" section to AGENTS.md capturing project- specific best practices (Signal2, string encoding, atomic saving). - Add a "Development Tips" section to AGENTS.md with advice on tracing data flow and running specific tests.
- Create docs/architecture.md: Detailed technical overview covering the proxy pipeline, PathMachine states, MapStorage, rendering/shader architecture (FBO, UBO, multisampling), and MUD integration. - Include a developer task guide and a glossary with a link to MUME's GMCP documentation. - Update AGENTS.md: Orientation, prescriptive coding guidelines (Signal2, string encoding, atomic saving), and development tips for tracing data flow and testing. - Ensure cross-linking between BUILD.md, AGENTS.md, and architecture.md for a seamless developer experience.
- Create docs/architecture.md: Detailed technical overview covering the proxy pipeline, PathMachine states, MapStorage, rendering/shader architecture (FBO, UBO, multisampling), and MUD integration. - Include a developer task guide and a glossary with a link to MUME's GMCP documentation and clarified MPI/MUME.Client terminology. - Update AGENTS.md: Orientation, prescriptive coding guidelines (Signal2, string encoding, atomic saving), and development tips. - Ensure cross-linking between BUILD.md, AGENTS.md, and architecture.md.
- Create docs/architecture.md: Detailed technical overview covering the proxy pipeline, PathMachine states, MapStorage, rendering/shader architecture (FBO, UBO, multisampling), and MUD integration. - Include a developer task guide and a glossary with verified terminology and a link to MUME's GMCP documentation. - Update AGENTS.md: Orientation, prescriptive coding guidelines (Signal2, string encoding, atomic saving), and development tips. - Ensure cross-linking between BUILD.md, AGENTS.md, and architecture.md.
nschimme
force-pushed
the
master
branch
3 times, most recently
from
May 21, 2026 23:06
ae664f2 to
bcd8fca
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This change introduces a high-level architecture overview in
docs/architecture.mdto help developers and AI agents quickly understand the system's structure, particularly the proxy communication pipeline. It also updatesAGENTS.mdwith a link to this documentation and adds a new "Coding Guidelines" section. These guidelines capture essential project-specific knowledge, such as the use of theSignal2system, UTF-8 string encoding requirements, and atomic file saving patterns, ensuring better consistency and fewer bugs in future contributions.PR created automatically by Jules for task 4212318795681793304 started by @nschimme
Summary by Sourcery
Add high-level architecture documentation and agent-facing coding guidelines to improve contributors’ understanding of the system and ensure consistent implementation practices.
Documentation: